home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 July: Mac OS SDK / Dev.CD Jul 96 SDK / Dev.CD Jul 96 SDK1.toast / Development Kits (Disc 1) / AOCE / Development Tools / Sample Code / Standard Catalog Package / DTS AddressOMatic / Src / AddressOMatic.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-06-17  |  17.0 KB  |  467 lines  |  [TEXT/KAHL]
  1. /*                                    AddressOMatic.h                                */
  2. /*
  3.  * AddressOMatic
  4.  * AddressOMatic.h
  5.  * Copyright © 1993 Apple Computer Inc. All rights reserved.
  6.  * AddressOMatic is a Trademark of Apple Computer Inc.
  7.  *
  8.  * These are the public definitions for the AddressOMatic.
  9.  */
  10. #ifndef _AddressOMatic_
  11. #define _AddressOMatic_
  12. #ifndef THINK_C                /* MPW includes            */
  13. #include <Menus.h>
  14. #include <TextEdit.h>
  15. #include <Types.h>
  16. #include <Windows.h>
  17. #endif
  18. #include <OCE.h>
  19. #include <OCEAuthDir.h>
  20. #include <OCEStandardDirectory.h>
  21. #include <OCEErrors.h>
  22.  
  23. /*
  24.  * Define ENABLE_TYPEIN to get type-in definitions. If undefined, no typein
  25.  * processing is provided whatsoever. I.e., string definitions must be changed.
  26.  * Note: MPW Rez does not process #if ENABLE_TYPEIN
  27.  */
  28. // #undef ENABLE_TYPEIN
  29. #define ENABLE_TYPEIN
  30.  
  31. /*
  32.  * This "random" number is used to create the type-in popup menu. It defines
  33.  * the start of a range of numbers (one for each open window).
  34.  * The user application must not create a menu with this menu id value
  35.  * or any value slightly larger as one higher value is consumed for each
  36.  * window that is opened.
  37.  */
  38. #define kAOMPrivateMenuID        11640        /* Useless random number            */
  39. /*
  40.  * 'STR#' stringsResID (parameter to NewSDPPanel)
  41.  * These index strings that we need for help text etc. The application must
  42.  * provide a STR# resource with the necessary text.
  43.  */
  44. enum {
  45.     /*
  46.      * Pane title strings (9 pt Geneva bold, centered)
  47.      */    
  48.     kAOMPDTitleString = 1,            /* "Personal Catalog"                        */
  49.     kAOMPanelTitleString,            /* "Catalog Browser"                        */
  50.     kAOMFindTitleString,            /* "Find Address"                            */
  51.     /*
  52.      * Button strings for the AOM selection buttons.
  53.      * The "Done" button is always enabled. If you put the AddressOMatic in
  54.      * its own window, you can eliminate this button and use a close box instead.
  55.      * The "Done" button does not interact with the SDP browser panels.
  56.      */
  57.     kAOMDoneButtonString,            /* "Done"        <Opt> etc. ignored            */
  58.     /*
  59.      * The "To" button has many manifestations. In the following, "(unchanged)"
  60.      * means that the button text is not modified. I.e., if you select a folder
  61.      * in the browser, then click on "nothing" the To button is disabled, but
  62.      * still shows "Save".
  63.      *    Browser, Personal Directory, and Type-In Panel
  64.      *        Selection        Option Button    Text        Enabled
  65.      *        Nothing            Off                (unchanged)    No
  66.      *        Nothing            On                (unchanged)    No
  67.      *        Folder            Off                "Open"        Yes
  68.      *        Folder            On                "Save"        Yes
  69.      *        Record            Off                "To"        Yes
  70.      *        Record            On                "Save"        Yes
  71.      *    Find Panel
  72.      *        Selection        Option Button    Text        Enabled
  73.      *        Nothing            Any                (unchanged)    No
  74.      *        Has Find Text    Any, Stopped    "Find"        Yes
  75.      *        Has Find Text    Any, Finding    "Stop"        Yes
  76.      *        Has Selection    Off, Stopped    "To"        Yes
  77.      *        Has Selection    On, Stopped        "Save"        Yes
  78.      */
  79.     kAOMToButtonString,                /* "To"            <Opt> off, record selected    */
  80.     kAOMOpenButtonString,            /* "Open"        <Opt> off, folder selected    */
  81.     kAOMSaveButtonString,            /* "Save"        <Opt> on, item selected        */
  82.     kAOMFindButtonString,            /* "Find"         <Opt> ignored                */
  83.     kAOMStopButtonString,            /* "Stop"        <Opt> ignored                */
  84.     /*
  85.      * The "CC" button has two manifestations. It is enabled if the "To" button
  86.      * shows "To" or "Save" and is enabled if a record is selected. It is disabled
  87.      * if the panel is currently finding (the "To" button shows "Find" or "Stop").
  88.      */
  89.     kAOMCCButtonString,                /* "CC"         <Opt> off, record selected    */
  90.     kAOMOptCCButtonString,            /* "BCC"        <Opt> on, record selected    */
  91.     /*
  92.      * Find panel item labels
  93.      */
  94.     kAOMFindArgLabelString,            /* "Find"                                    */
  95.     kAOMFindDirLabelString,            /* "Search"                                    */
  96. #ifdef ENABLE_TYPEIN
  97.     kAOMTypeInTitleString,            /* "Type-in Addressing"                        */
  98.     kAOMTypeInAddrLabelString,        /* "Address"                                */
  99.     kAOMTypeInDirLabelString,        /* "Catalog"                                */
  100. #endif
  101.     /*
  102.      * Personal Directory has no labels
  103.      */
  104.     kAOMLastString
  105. };
  106.  
  107. /*
  108.  * These mode bits configure the Address-O-Matic panel: If a radio button (PD,
  109.  * Panel, Show, TypeIn) is disabled, it is shown, but always disabled. If one of
  110.  * the action buttons (Done, CC, To) is not shown, it is not shown (and not
  111.  * available). It might make sense, however, to allow configuring the panel with
  112.  * missing radio buttons, but this brings up positioning issues I'd rather avoid.
  113.  *
  114.  * kAOMEnablePDBit, kAOMEnablePanelBit, kAOMEnableFindBit, kAOMEnableTypeInBit
  115.  * and kAOMUnknownMode are also used for the initial radio button mode.
  116.  */
  117. enum {
  118.     kAOMUnknownMode            = 0xFFFF,
  119.     kAOMEnablePDBit            = 0,
  120.     kAOMEnablePanelBit,
  121.     kAOMEnableFindBit,
  122. #ifdef ENABLE_TYPEIN
  123.     kAOMEnableTypeInBit,
  124. #endif
  125.     kAOMShowDoneButtonBit,
  126.     kAOMShowCCButtonBit,
  127.     kAOMShowToButtonBit
  128. };
  129. typedef unsigned short        AOMModeBit;
  130.  
  131. enum {
  132.     kAOMEnablePDMask        = (1L << kAOMEnablePDBit),
  133.     kAOMEnablePanelMask        = (1L << kAOMEnablePanelBit),
  134.     kAOMEnableFindMask        = (1L << kAOMEnableFindBit),
  135. #ifdef ENABLE_TYPEIN
  136.     kAOMEnableTypeInMask    = (1L << kAOMEnableTypeInBit),
  137. #endif
  138.     kAOMShowDoneButtonMask    = (1L << kAOMShowDoneButtonBit),
  139.     kAOMShowCCButtonMask    = (1L << kAOMShowCCButtonBit),
  140.     kAOMShowToButtonMask    = (1L << kAOMShowToButtonBit),
  141. #ifdef ENABLE_TYPEIN
  142.     kAOMAllRadioButtons        = (
  143.             kAOMEnablePDMask
  144.             | kAOMEnablePanelMask
  145.             | kAOMEnableFindMask
  146.             | kAOMEnableTypeInMask
  147.         ),
  148.     kAOMStandardRadioButtons = (    /* "Standard" excludes the type-in button    */    
  149.             kAOMEnablePDMask
  150.             | kAOMEnablePanelMask
  151.             | kAOMEnableFindMask
  152.         ),
  153. #else
  154.     kAOMAllRadioButtons        = (
  155.             kAOMEnablePDMask
  156.             | kAOMEnablePanelMask
  157.             | kAOMEnableFindMask
  158.         ),
  159.     kAOMStandardRadioButtons = (    /* "Standard" excludes the type-in button    */    
  160.             kAOMEnablePDMask
  161.             | kAOMEnablePanelMask
  162.             | kAOMEnableFindMask
  163.         ),
  164. #endif
  165.     kAOMAllActionButtons    = (
  166.             kAOMShowDoneButtonMask | kAOMShowCCButtonMask | kAOMShowToButtonMask
  167.         )
  168. };
  169. typedef unsigned long        AOMModeMask;
  170.  
  171. /*
  172.  * Index for item rectangles in the AOM panel. This is needed for Help strings,
  173.  * as well as mouse hits. Note that item 1 corresponds to Help item 1, etc. The
  174.  * application program does not need to be concerned with this information: it
  175.  * is used internally, but is defined here to allocate the proper amount of
  176.  * memory.
  177.  */
  178. typedef enum {
  179.     kAOMPanelItem            = 0,
  180.     kAOMPDButtonItem,
  181.         kAOMFirstRadio        = kAOMPDButtonItem,
  182.     kAOMDirButtonItem,
  183.     kAOMFindButtonItem,
  184. #ifdef ENABLE_TYPEIN
  185.     kAOMTypeInButtonItem,
  186.         kAOMLastRadio        = kAOMTypeInButtonItem,
  187. #else
  188.         kAOMLastRadio        = kAOMFindButtonItem,
  189. #endif
  190.         kAOMRadioButtons    = kAOMLastRadio - kAOMFirstRadio + 1,
  191.     kAOMDoneButtonItem        = kAOMLastRadio + 1,
  192.         kAOMFirstButton        = kAOMDoneButtonItem,
  193.     kAOMCCButtonItem,
  194.     kAOMToButtonItem,
  195.         kAOMLastButton        = kAOMToButtonItem,
  196.     kAOMSDPPanelItem,
  197.     kAOMSDPPanelExterior,                /* SDP stuff with slop for focus rect    */
  198. #ifdef ENABLE_TYPEIN
  199.     kAOMTypeInAddrLabelItem,            /* "Address"                            */
  200.     kAOMTypeInDirLabelItem,                /* "Directory"                            */
  201.     kAOMTypeInAddressItem,                /* Address TextEdit record                */
  202.     kAOMTypeInDirectoryItem,            /* Directory popup control                */
  203. #endif
  204.     kAOMSpinnerItem,
  205.     kAOMPanelLabelItem,
  206.     kAOMInteriorAreaItem,    /* Inside of the drop shadow            */
  207.     kAOMItemRectCount
  208. } AOMItemIndex;
  209.  
  210. /*
  211.  * These are the values for the AOMPanelEvent "whatHappened" parameter. This
  212.  * is a synthesis of Standard Mail and Standard Directory event processing.
  213.  * These are bit numbers. The application should use the mask values below.
  214.  *
  215.  *    kAOMAppMustHandleEventBit
  216.  *        If TRUE, the application must process this event. It may also have
  217.  *        been processed by the AOM Panel.
  218.  *    kAOMPanelBecomesTargetBit
  219.  *        The user clicked in the AOM Panel. kAOMAppMustHandleEventBit is FALSE,
  220.  *        but the application may wish to handle this event by un-hiliting
  221.  *        window selections or stopping insertion point blinking.
  222.  *    kAOMAppBecomesTargetBit
  223.  *        The user was working in the AOM Panel, but now clicked in the window
  224.  *        content area (outside of the AOM Panel). kAOMAppMustHandleEventBit is
  225.  *        set TRUE.
  226.  *    kAOMFindInProgressBit
  227.  *        The AOM Panel is currently finding. You should set a lower WaitNextEvent
  228.  *        sleep time to give the panel more time to search.
  229.  *    kAOMSelectedAnItemBit
  230.  *        The AOM Panel is processing a Standard Directory Browser panel. This
  231.  *        bit is set if the call to SDPPanelEvent returned kSDPSelectedAnItem.
  232.  *    kAOMChangedSelectionBit
  233.  *        The AOM Panel is processing a Standard Directory Browser panel. This
  234.  *        bit is set if the call to SDPPanelEvent returned kSDPChangedSelection.
  235.  *    kAOMItemIsSelectedBit
  236.  *        The AOM Panel is processing a Standard Find panel. This bit is set if
  237.  *        the call to SDPFindPanelState set kSDPItemIsSelectedBit.
  238.  *    kAOMFindTextExistsBit
  239.  *        The AOM Panel is processing a Standard Find panel. This bit is set if
  240.  *        the call to SDPFindPanelState set kSDPFindTextExistsBit.
  241.  *    kAOMDoneButtonHitBit
  242.  *    kAOMCCButtonHitBit
  243.  *    kAOMBCCButtonHitMask
  244.  *    kAOMToButtonHitBit
  245.  *    kAOMSaveButtonHitMask
  246.  *        The associated button was pressed; kAOMAppMustHandleEventBit is set TRUE.
  247.  */
  248. enum {
  249.     kAOMAppMustHandleEventBit,                    /* App ignores event if FALSE    */
  250.     kAOMPanelBecomesTargetBit,                    /* Click in AOM Panel            */
  251.     kAOMAppBecomesTargetBit,                    /* Click outside AOM Panel        */
  252.     kAOMFindInProgressBit,                        /* Currently finding            */
  253.     kAOMSelectedAnItemBit,                        /* kSDPSelectedAnItem            */
  254.     kAOMChangedSelectionBit,                    /* kSDPChangedSelection            */
  255.     kAOMDoneButtonHitBit,                        /* User hit "done"                */
  256.     kAOMCCButtonHitBit,                            /* User hit "cc"                */
  257.     kAOMBCCButtonHitBit,                        /* User hit <OPT> "cc"            */
  258.     kAOMToButtonHitBit,                            /* User hit "to"                */
  259.     kAOMSaveButtonHitBit                        /* User hit <OPT> "To"            */
  260. };
  261. /*
  262.  * The application should use the following mask bits to test event state.
  263.  * These are #defines to avoid Ansi C "enums are int" problems.
  264.  */
  265. #define    kAOMAppMustHandleEventMask        (1L << kAOMAppMustHandleEventBit)
  266. #define    kAOMPanelBecomesTargetMask        (1L << kAOMPanelBecomesTargetBit)
  267. #define    kAOMAppBecomesTargetMask        (1L << kAOMAppBecomesTargetBit)
  268. #define kAOMFindInProgressMask            (1L << kAOMFindInProgressBit)
  269. #define    kAOMSelectedAnItemMask            (1L << kAOMSelectedAnItemBit)
  270. #define    kAOMChangedSelectionMask        (1L << kAOMChangedSelectionBit)
  271. #define kAOMDoneButtonHitMask            (1L << kAOMDoneButtonHitBit)
  272. #define kAOMCCButtonHitMask                (1L << kAOMCCButtonHitBit)
  273. #define kAOMBCCButtonHitMask            (1L << kAOMBCCButtonHitBit)
  274. #define kAOMToButtonHitMask                (1L << kAOMToButtonHitBit)
  275. #define kAOMSaveButtonHitMask            (1L << kAOMSaveButtonHitBit)
  276. #define kAOMAnyActionButtonHitMask    (    \
  277.         kAOMCCButtonHitMask                \
  278.         | kAOMBCCButtonHitMask            \
  279.         | kAOMToButtonHitMask            \
  280.         | kAOMSaveButtonHitMask            \
  281.     )
  282.  
  283. typedef unsigned long        AOMPanelState;
  284.  
  285. /*
  286.  * This is the information the AddressOMatic needs to process user requests.
  287.  * Some of this information persists between calls. Although this is
  288.  * visible to applications, it should be treated as a private structure
  289.  * (i.e., applications should call functions to manage data, rather than
  290.  * change it directly).
  291.  */
  292. typedef struct AddressOMaticRecord {
  293.     WindowPtr            window;                    /* The AOM is in this window    */
  294.     SDPPanelHandle        pdPanel;                /* -> Personal Directory Panel    */
  295.     SDPPanelHandle        browsePanel;            /* -> SDP panel, if any            */
  296.     SDPFindPanelHandle    findPanel;                /* -> Find panel, if any        */
  297.     SDPSelectionState    browseSelectionState;    /* Browser state                */
  298.     SDPFindPanelState    findPanelState;            /* Find state                    */
  299.     SDPSelectionState    oldBrowseSelectionState; /* Previous browser state        */
  300.     SDPFindPanelState    oldFindPanelState;        /* Previous find state            */
  301.     /*
  302.      * Button controls. The radio buttons that select what is displayed are
  303.      * handled internally.
  304.      */
  305.     ControlHandle        doneButton;                /* "done"                        */
  306.     ControlHandle        ccButton;                /* "cc" or "bcc"                */
  307.     ControlHandle        toButton;                /* "to" or "save"                */
  308. #ifdef ENABLE_TYPEIN
  309.     RStringPtr            typeInRecordType;        /* What does type-in return?    */
  310.     ControlHandle        typeInPopup;            /* Directories popup CDEF        */
  311.     TEHandle            typeInAddress;            /* Address text                    */
  312.     MenuHandle            popupMenu;                /* Private menu handle            */
  313.     short                popupMenuID;            /* Private menu id                */
  314.     Boolean                typeInVisible;            /* TRUE if stuff is on screen    */
  315.     struct _AOMDirectoryInfoRecord (**dirInfoHdl); /* Our directories            */
  316. #endif
  317.     AuthIdentity        identity;                /* Needed for type-in only        */
  318.     const RStringPtr    *typesList;                /* Active types                    */
  319.     unsigned long        typeCount;                /* Number of active types        */
  320.     void                *refCon;                /* User-controlled value        */
  321.     /*
  322.      * These variables manage the "in progress" spinner.
  323.      */
  324.     short                animationSICNIndex;        /* Current animation SICN        */
  325.     unsigned long        nextAnimation;            /* When to update animation        */
  326.     /*
  327.      * These values manage active operation state.
  328.      */
  329.     Boolean                isVisible;                /* AOM is currently visible        */
  330.     Boolean                isEnabled;                /* AOM is currently active        */
  331.     Boolean                isTarget;                /* User clicked in AOM Panel    */
  332.     AOMModeBit            currentMode;            /* What is the user doing now?    */
  333.     short                optKeyDown;                /* Last event set option key    */
  334.     Boolean                buttonUpdateNeeded;        /* TRUE updates action buttons    */
  335.     Boolean                enableToButton;            /* TRUE if to button is alive    */
  336.     Boolean                enableCCButton;            /* TRUE if cc button is alive    */
  337.     short                toButtonString;            /* String index of "To" button    */
  338.     short                ccButtonString;            /* String index of "CC" button    */
  339.     short                stringsResID;            /* Where are our strings        */
  340.     Boolean                helpAvailable;            /* Is Balloon Help present?        */
  341.     Boolean                radioEnable[kAOMRadioButtons];    /* TRUE if enabled        */
  342.     /*
  343.      * This Rect vector manages the shape of the panel and all its elements.
  344.      * The zero'th item is the panel rectangle. All values are in Window
  345.      * coordinates. If the panel moves within the window, all items must be offset.
  346.      */
  347.     Rect                itemRect[kAOMItemRectCount]; /* Panel and item layout    */
  348. } AddressOMaticRecord, *AddressOMaticPtr;
  349.  
  350. /*
  351.  * Create an AddressOMatic panel. If the application disables one of the
  352.  * radio buttons, it should pass NULL or zero for the affected parameter.
  353.  */
  354. pascal OSErr                    AOMNewPanel(
  355.         AddressOMaticPtr            *aomPanel,            /* Record stored here    */
  356.         WindowPtr                    window,                /* Put into this window    */
  357.         const Rect                    *bounds,            /* Shape and position    */
  358.         Boolean                        visible,            /* Initially visible    */
  359.         Boolean                        enabled,            /* Initially enabled    */
  360.         AuthIdentity                identity,            /* Initial identity        */
  361.         const RStringPtr            *typesList,            /* Types to select        */
  362.         unsigned long                typeCount,            /* Number of types        */
  363.         void                        *refCon,            /* App owns this value    */
  364.         AOMModeMask                    enableModeMask,        /* What can user do?    */
  365.         AOMModeBit                    initialMode,        /* Starting with?        */
  366.         short                        stringsResID,        /* Labelling strings    */
  367.         short                        browserHelpStringID, /* Browser help string    */
  368.         short                        pdHelpStringID,        /* Personal Cat. help    */
  369.         short                        findHelpStringID,    /* Find panel help        */
  370.         /*
  371.          * The following parameters configure the SDPPanel and Personal Directory
  372.          * Browser.
  373.          */
  374.         const PackedRLI                *initialRLI,        /* Initial selection    */
  375.         DirEnumChoices                enumFlags,            /* Enumeration flags    */
  376.         DirMatchWith                matchTypeHow,        /* Enumeration mode        */
  377.         /*
  378.          * The following parameter configures the SDPFindPanel. Focus is always
  379.          * initially in the text area.
  380.          */
  381.         short                        simultaneousSearchCount
  382. #ifdef ENABLE_TYPEIN
  383.         ,
  384.         /*
  385.          * The following parameter configures the TypeIn callback
  386.          */
  387.         const RStringPtr            typeInRecordType        /* What does it return    */
  388. #endif
  389.     );
  390.  
  391.  
  392. /*
  393.  * Return the minimum width and height of the panel. The panel need not
  394.  * have been created. This function does not have an error status.
  395.  */
  396. void                            AOMGetDimensions(
  397.         short                        *minimumWidth,
  398.         short                        *minimumHeight
  399.     );
  400. /*
  401.  * Clean up the mess.
  402.  */
  403. pascal OSErr                    AOMDisposePanel(
  404.         AddressOMaticPtr            aomPanel            /* The panel            */
  405.     );
  406.  
  407. /*
  408.  * Redraw the panel. Called on update events. Set drawRgn to NULL
  409.  * to redraw the entire panel. Normally, it is set to the window's
  410.  * GrafPort's visRgn.
  411.  */
  412. pascal OSErr                    AOMUpdatePanel(
  413.         AddressOMaticPtr            aomPanel,
  414.         RgnHandle                    drawRgn
  415.     );
  416.  
  417. pascal OSErr                    AOMAdjustPanel(
  418.         AddressOMaticPtr            aomPanel,
  419.         const Rect                    *boundsRect
  420.     );
  421. /*
  422.  * TBS:
  423.  * Set identity
  424.  * Set Path, Get Path, Get Path Length
  425.  * Set SDP Panel Balloon Help
  426.  * Set SDP Panel Find Help
  427.  * Set SDP Type In Help        (Dialog help format)
  428.  * Become Target (for tabbing, param is "select Last"
  429.  * or "select first") -- this is needed because the
  430.  * number of active elements may change depending on
  431.  * the radio button state. We can't allow the application
  432.  * to select a random target.
  433.  */
  434.  
  435. /*
  436.  * AOMExtractSelection does all the work of getting the current selection.
  437.  * On return:
  438.  *        result            error code from OCE, or kOCENoSuchRecord if there is
  439.  *                        no current selection.
  440.  *        selectionSize    contains the size of the buffer that was created.
  441.  *        selection        The address of a PackedDSSpecPtr that, on return,
  442.  *                        will contain a pointer to the selection.
  443.  */ 
  444. pascal OSErr                    AOMExtractSelection(
  445.         AddressOMaticPtr            aomPanel,
  446.         unsigned short                *selectionSize,
  447.         PackedDSSpecPtr                *selection
  448.     );
  449. /*
  450.  * Call on every event
  451.  */
  452. pascal OSErr                    AOMPanelEvent(
  453.         AddressOMaticPtr            aomPanel,            /* The panel            */
  454.         const EventRecord            *theEvent,            /* The event            */
  455.         AOMPanelState                *whatHappened        /* Result                */
  456.     );
  457.  
  458. /*
  459.  * This should be done by using the identity queue instead.
  460.  */
  461. pascal OSErr                    AOMSetIdentity(
  462.         AddressOMaticPtr            aomPanel,            /* The panel            */
  463.         AuthIdentity                userIdentity
  464.     );
  465.  
  466. #endif    /* _AddressOMatic_    */
  467.